chore(gas): add overview and history docs #3879

MasterPtato · 2026-01-13T21:41:59Z

No description provided.

MasterPtato · 2026-01-13T21:42:35Z

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

_{An organization admin has enabled the Graphite Merge Queue in this repository.} _{Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.}

This stack of pull requests is managed by Graphite. Learn more about stacking.

pkg-pr-new · 2026-01-13T21:44:19Z

More templates

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/cloudflare-workers@3879

@rivetkit/db

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/db@3879

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/framework-base@3879

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/next-js@3879

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/react@3879

rivetkit

pnpm add https://pkg.pr.new/rivet-dev/rivet/rivetkit@3879

@rivetkit/sql-loader

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sql-loader@3879

@rivetkit/virtual-websocket

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/virtual-websocket@3879

@rivetkit/engine-runner

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner@3879

@rivetkit/engine-runner-protocol

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner-protocol@3879

commit: 7d75756

claude · 2026-01-13T21:45:02Z

PR Review: Gasoline Documentation

This PR adds comprehensive documentation for Gasoline's core concepts. Overall, this is a high-quality documentation contribution that will significantly help developers understand the durable execution engine.

✅ Strengths

Excellent Structure: Breaking the old monolithic GASOLINE.md into focused documents (OVERVIEW, WORKFLOW_HISTORY, etc.) greatly improves discoverability and maintainability.
Clear Explanations: The workflow history location system is complex, and the documentation does an excellent job explaining it with concrete examples.
Practical Examples: The Activities section's bad composition example (OVERVIEW.md:43-53) effectively illustrates common pitfalls.
Good Technical Accuracy: The code example in WORKFLOW_HISTORY.md accurately demonstrates version-based conditional execution.

📝 Minor Issues & Suggestions

Documentation Content

Inconsistent Actor Terminology (OVERVIEW.md:6)
- Line 6: "Workflows - Similar to the concept of actors."
- The old version explicitly mentioned "(not Rivet Actors)" to avoid confusion with Rivet's actor system
- Suggestion: Consider re-adding this clarification: "Similar to the concept of actors (not Rivet Actors)" to prevent confusion with Pegboard actors
Missing Newline (OVERVIEW.md:86)
- The file should end with a newline character per standard conventions
- Most editors and formatters expect this
Clarity Enhancement (WORKFLOW_HISTORY.md:7)
- "Each coordinate is a set of ordinates"
- Could be clearer: "Each coordinate consists of one or more ordinates"
Grammar (WORKFLOW_HISTORY.md:105)
- "Loops structure event history with 2 nested branches"
- Minor: Could be "Loops structure event history with two nested branches" (spell out small numbers in prose)

Code Changes

Comment Clarity (engine/packages/gasoline/src/db/kv/mod.rs:980)
- Changed "interpreted as u128" to "by internal representation"
- While "by internal representation" is more accurate, it's less specific
- Suggestion: Consider "by internal representation (u128 byte ordering)" to retain specificity

TODOs

Placeholder Files
- DESIGN_GUIDE.md, GOTCHAS.md, and OPERATIONS.md are all TODO placeholders
- Consider: Creating issues to track these documentation items, or removing them until ready to populate
- Placeholder files in main can create confusion about completeness

🎯 Recommendations

High Priority:

Add back the "(not Rivet Actors)" clarification to avoid terminology confusion
Add trailing newline to OVERVIEW.md

Medium Priority:

Consider whether to keep or remove placeholder TODO files
Enhance the comment in mod.rs to be more specific about the ordering

Low Priority:

Minor grammar/clarity improvements in WORKFLOW_HISTORY.md

Summary

This is solid documentation work. The content is technically accurate, well-organized, and pedagogically effective. The main concerns are around maintaining consistency with terminology conventions (Rivet Actors) and deciding whether to include placeholder files.

The typo fix in HIBERNATING_WS.md is good.

Verdict: Approved with minor suggestions for consideration. The documentation significantly improves upon the original GASOLINE.md file.

docs/engine/GASOLINE/OVERVIEW.md

abcxff · 2026-01-13T22:02:16Z

docs/engine/GASOLINE/OVERVIEW.md

+	- Separate the transactions into 2 activities
+
+## Signals
+


Nice how it explains a bit more of how it actually works. Might be good to say blatanlty how signals are the only form of durable/guaranteed communication and they’re consumption is guaranteed ( is it?)

Updated to say "only". Signal consumption is not guaranteed, the wf needs to listen to the signals to receive them

abcxff · 2026-01-13T22:05:33Z

docs/engine/GASOLINE/OVERVIEW.md

+
+Signals can be sent to a workflow if you know its name and a subset of its tags.
+
+Internally, it is more efficient to order signal tags in a manner of most unique to least unique:


Is this Gotchas worthy?

graphite-app · 2026-01-14T23:40:15Z

Merge activity

Jan 14, 11:40 PM UTC: MasterPtato added this pull request to the Graphite merge queue.
Jan 14, 11:41 PM UTC: CI is running for this pull request on a draft pull request (#3908) due to your merge queue CI optimization settings.
Jan 14, 11:42 PM UTC: Merged by the Graphite merge queue via draft PR: #3908.

MasterPtato requested review from NathanFlurry and abcxff January 13, 2026 21:42

MasterPtato mentioned this pull request Jan 13, 2026

fix(otel): enrich http traces #3878

Closed

abcxff reviewed Jan 13, 2026

View reviewed changes

docs/engine/GASOLINE/OVERVIEW.md Outdated Show resolved Hide resolved

abcxff reviewed Jan 13, 2026

View reviewed changes

MasterPtato force-pushed the 01-13-chore_gas_add_overview_and_history_docs branch 2 times, most recently from ea05c93 to c2f846e Compare January 14, 2026 02:05

MasterPtato force-pushed the 01-13-fix_otel_enrich_http_traces branch 2 times, most recently from a35f0d9 to e88b75c Compare January 14, 2026 02:53

MasterPtato force-pushed the 01-13-chore_gas_add_overview_and_history_docs branch 2 times, most recently from 0738934 to 8b91b37 Compare January 14, 2026 03:06

MasterPtato force-pushed the 01-13-fix_otel_enrich_http_traces branch from e88b75c to 74129c7 Compare January 14, 2026 03:06

NathanFlurry approved these changes Jan 14, 2026

View reviewed changes

MasterPtato force-pushed the 01-13-chore_gas_add_overview_and_history_docs branch from 8b91b37 to f65fde5 Compare January 14, 2026 19:47

MasterPtato force-pushed the 01-13-fix_otel_enrich_http_traces branch from 74129c7 to c3c6740 Compare January 14, 2026 19:47

MasterPtato force-pushed the 01-13-chore_gas_add_overview_and_history_docs branch from f65fde5 to ffb8072 Compare January 14, 2026 20:01

MasterPtato force-pushed the 01-13-fix_otel_enrich_http_traces branch from c3c6740 to cdb8231 Compare January 14, 2026 20:01

This was referenced Jan 14, 2026

fix(engine-runner): handle shutdown close codes correctly #3896

Closed

fix(pegboard): cache none runner pool errors too #3899

Closed

MasterPtato force-pushed the 01-13-chore_gas_add_overview_and_history_docs branch from ffb8072 to 654b4e9 Compare January 14, 2026 22:45

MasterPtato force-pushed the 01-13-fix_otel_enrich_http_traces branch from cdb8231 to 1353291 Compare January 14, 2026 22:45

MasterPtato force-pushed the 01-13-chore_gas_add_overview_and_history_docs branch from 654b4e9 to c023ef5 Compare January 14, 2026 22:47

MasterPtato force-pushed the 01-13-fix_otel_enrich_http_traces branch 2 times, most recently from 921ccb3 to e8bbcf8 Compare January 14, 2026 22:52

MasterPtato force-pushed the 01-13-chore_gas_add_overview_and_history_docs branch from c023ef5 to af232ee Compare January 14, 2026 22:52

MasterPtato force-pushed the 01-13-fix_otel_enrich_http_traces branch from e8bbcf8 to d8a0135 Compare January 14, 2026 23:02

MasterPtato force-pushed the 01-13-chore_gas_add_overview_and_history_docs branch from af232ee to 1c80e13 Compare January 14, 2026 23:02

MasterPtato force-pushed the 01-13-fix_otel_enrich_http_traces branch from d8a0135 to 116ea58 Compare January 14, 2026 23:07

MasterPtato force-pushed the 01-13-chore_gas_add_overview_and_history_docs branch from 1c80e13 to 5889ab3 Compare January 14, 2026 23:07

chore(gas): add overview and history docs

7d75756

MasterPtato force-pushed the 01-13-fix_otel_enrich_http_traces branch from 116ea58 to 708a38f Compare January 14, 2026 23:39

MasterPtato force-pushed the 01-13-chore_gas_add_overview_and_history_docs branch from 5889ab3 to 7d75756 Compare January 14, 2026 23:39

graphite-app bot pushed a commit that referenced this pull request Jan 14, 2026

chore(gas): add overview and history docs (#3879)

007cd5d

graphite-app bot closed this Jan 14, 2026

graphite-app bot deleted the 01-13-chore_gas_add_overview_and_history_docs branch January 14, 2026 23:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

chore(gas): add overview and history docs #3879

chore(gas): add overview and history docs #3879

Uh oh!

MasterPtato commented Jan 13, 2026

Uh oh!

MasterPtato commented Jan 13, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Jan 13, 2026 •

edited

Loading

Uh oh!

claude bot commented Jan 13, 2026 •

edited

Loading

Uh oh!

Uh oh!

abcxff Jan 13, 2026

Uh oh!

MasterPtato Jan 13, 2026

Uh oh!

abcxff Jan 13, 2026

Uh oh!

MasterPtato Jan 13, 2026

Uh oh!

graphite-app bot commented Jan 14, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		Signals can be sent to a workflow if you know its name and a subset of its tags.

		Internally, it is more efficient to order signal tags in a manner of most unique to least unique:

chore(gas): add overview and history docs #3879

chore(gas): add overview and history docs #3879

Uh oh!

Conversation

MasterPtato commented Jan 13, 2026

Uh oh!

MasterPtato commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

How to use the Graphite Merge Queue

Uh oh!

pkg-pr-new bot commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude bot commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review: Gasoline Documentation

✅ Strengths

📝 Minor Issues & Suggestions

Documentation Content

Code Changes

TODOs

🎯 Recommendations

Summary

Uh oh!

Uh oh!

abcxff Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

MasterPtato Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

abcxff Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

MasterPtato Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

graphite-app bot commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge activity

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

MasterPtato commented Jan 13, 2026 •

edited

Loading

pkg-pr-new bot commented Jan 13, 2026 •

edited

Loading

claude bot commented Jan 13, 2026 •

edited

Loading

graphite-app bot commented Jan 14, 2026 •

edited

Loading